\latex{\section*{Overview}\addcontentsline{toc}{subsection}{Overview}}
\latex{\label {sec:overview}}

\begin {htmlonly}
This package contains classes to produce charts used in the Java software developed in the {\em simulation laboratory\/}
of the DIRO, at the Universite de Montreal.
\end {htmlonly}

This package provides tools for easy
construction, visualization, and customization
of XY plots, histograms, and empirical styled charts
from a Java program.
It uses and extends the free and ``open source''
JFreeChart tool to manage the
charts. JFreeChart is
distributed under the terms of the GNU Lesser General Public License
(LGPL), and can be found at \url{http://www.jfree.org/jfreechart/}.

This package also provides facilities
to export charts to PGF/TikZ source code, which can be included into
\LaTeX{} documents. TikZ is a free \LaTeX{}
package to produce pictures such as plots, and can be downloaded from
\url{http://sourceforge.net/projects/pgf}.

The user does not need to be familiar with the JFreeChart package
or the TikZ syntax to
use these tools, except if customization is required.
For this, one may see the API specification of JFreeChart, and
the reference manual of TikZ.

The two basic abstract classes of package \texttt{charts} are
\externalclass{umontreal.iro.lecuyer.charts}{XYChart} and
\externalclass{umontreal.iro.lecuyer.charts}{CategoryChart}. All other
charts inherit from one of these two. Charts are managed by
the mother class which contains the data tables in a
\texttt{*SeriesCollection} object, and the
information about $x$-axis and $y$-axis in
\externalclass{umontreal.iro.lecuyer.charts}{Axis} instances.
All these objects encapsulate JFreeChart instances along with some
additional TikZ-specific attributes.
The method
\externalmethod{umontreal.iro.lecuyer.charts}{XYChart}{view}{}
displays charts on screen while the method
\texttt{toLatex} formats and returns a
\externalclass{java.lang}{String}{} which contains the TikZ source
code that can be written to a \LaTeX{} file.

Several chart styles are available and each one is represented by a
 subclass of \externalclass{umontreal.iro.lecuyer.charts}{XYChart} or of
\externalclass{umontreal.iro.lecuyer.charts}{CategoryChart}.
The \externalclass{umontreal.iro.lecuyer.charts}{XYLineChart} uses
\externalclass{umontreal.iro.lecuyer.charts}{XYListSeriesCollection}
to plot curves and lines, the
\externalclass{umontreal.iro.lecuyer.charts}{HistogramSeries\-Collection}
class is used by
\externalclass{umontreal.iro.lecuyer.charts}{HistogramChart} to plot
histograms, and the
\externalclass{umontreal.iro.lecuyer.charts}{EmpiricalSeries\-Collection} is used by
\externalclass{umontreal.iro.lecuyer.charts}{EmpiricalChart} to plot empirical style charts. It is possible to draw a scatter plot or a box plot using
\externalclass{umontreal.iro.lecuyer.charts}{ScatterChart} or
\externalclass{umontreal.iro.lecuyer.charts}{BoxChart} respectively.
These concrete subclasses have similar APIs, but they are specialized for
different kinds of charts.

These charts can be customized using
\texttt{*SeriesCollection} subclasses and
\externalclass{umontreal.iro.lecuyer.charts}{Axis}.
First, one can use methods in
the \externalclass{umontreal.iro.lecuyer.charts}{XYChart} class for
setting the range values and a background grid.
One can also use the method
\texttt{getSeriesCollection()} for subclasses of charts to obtain
the dataset of the chart, which is represented by a
\texttt{*SeriesCollection} object.
This dataset can be customized in the following ways by calling
methods
on the series collection:
selecting color, changing
plot style (straight lines, curves, marks only, \ldots), putting marks
on points, setting a label and selecting the dash pattern (solid,
dotted, dashed, \ldots). The available properties depend on the type
of chart.
Moreover, objects representing the axes can be retrieved with
\externalmethod{umontreal.iro.lecuyer.charts}{XYChart}{getXAxis}{}
for the
$x$-axis, and
\externalmethod{umontreal.iro.lecuyer.charts}{XYChart}{getYAxis}{}
for  the $y$-axis.
By using methods in \externalclass{umontreal.iro.lecuyer.charts}{Axis},
many customizations are possible: setting a label to the axis,
setting ticks labels and values (auto ticks, periodical ticks or
manually defined ticks) and changing the twin axis position on the
current axis to select where axes must appear.
These settings are independent for each axis.

Each chart object from SSJ encapsulates a JFreeChart object: a
\externalclass{umontreal.iro.lecuyer.charts}{XYChart} instance contains a
\texttt{JFreeChart} instance from JFreeChart API, a
\texttt{*SeriesCollection} contains a
\texttt{XYDataset} and a \texttt{XYItem\-Renderer}, and finally an
\externalclass{umontreal.iro.lecuyer.charts}{Axis} contains a
\texttt{NumberAxis}. So any parameter proposed by
JFreeChart  is reachable through
getter methods.  However,
changing the JFreeChart parameters directly may have no impact
on the produced TikZ source code.

The two special classes
\externalclass{umontreal.iro.lecuyer.charts}{ContinuousDistChart} and
\externalclass{umontreal.iro.lecuyer.charts}{DiscreteDistIntChart}
can be used to plot probability densities, mass functions,
and cumulative probabilities for continuous or discrete distributions,
which are implemented in package
\externalclass{umontreal.iro.lecuyer}{probdist} of SSJ.


The package \texttt{charts} provides additional tools for formatting
 data plot, and creating charts with multiple datasets. The
\externalclass{umontreal.iro.lecuyer.charts}{PlotFormat} class
offers basic tools to import and export data from files.
Supported file formats are GNUPlot and standard CSV, which is widely
used and accepted by most mathematical softwares such as
MATLAB and Mathematica. Customizing file input and output format is also possible.
Finally \externalclass{umontreal.iro.lecuyer.charts}{MultipleDatasetChart}
 provides tools to plot with different styles on the same chart.

\latex{\section*{Examples}\addcontentsline{toc}{subsection}{Examples}}
\latex{\label {sec:examples}}

\begin{htmlonly}
For a series of examples, see the \textbf{pdf} documentation.
\end{htmlonly}

\begin{latexonly}

The following examples demonstrate how to build charts with this package.

\lstinputlisting[label=lst:normalchart,%
caption={A simple example of chart creation},%
lineskip=-2pt,%
emph={getPoints,main}
]{exam/NormalChart.java}

\begin{figure}
\input{exam/NormalChart.tex}
\caption{The density of the standard normal.\label{fig:normalchart-res}}
\end{figure}


The first program, displayed in Listing~\ref{lst:normalchart},
shows the simplest way to export charts from data tables.
First, a curve is defined with regularly spaced $x$-coordinates
in method \texttt{getPoints}; it represents the curve
 $y = e^{-x^2/2}/\sqrt{2\pi}$, the density of the standard normal probability
 distribution. Arrays \texttt{points[0]} contain
the $x$-coordinates and \texttt{points[1]} the $y$-coordinates
of the points.
Figure~\ref{fig:normalchart-res} presents the resulting chart if the produced
TikZ code is added to a \LaTeX{} document using the \texttt{tikz}
package, and compiled using \LaTeX{} or Pdf\LaTeX.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

A simpler way to plot a
 probability density or a distribution function is to use the class
\externalclass{umontreal.iro.lecuyer.charts}{ContinuousDistChart}, as shown
in Listing~\ref{lst:normaldist}  where however, the normal density will be plotted
directly on the screen.

\lstinputlisting[label=lst:normaldist,%
caption={The normal density},%
lineskip=-1pt,%
emph={main}
]{exam/ContDistPlot.java}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The next example, displayed in Listing~\ref{lst:poissonchart}, plots the
probability mass function for a Poisson distribution with $\lambda= 50$
by simply creating an instance of
\externalclass{umontreal.iro.lecuyer.charts}{DiscreteDistIntChart}.
Figure~\ref{fig:poissonchart-res} presents the resulting chart obtained
from Pdf\LaTeX.

\begin{figure}
\input{exam/DistIntTest.tex}
\caption{The probabilities of the Poisson distribution with $\lambda= 50$.\label{fig:poissonchart-res}}
\end{figure}


\lstinputlisting[label=lst:poissonchart,%
caption={Probabilities of the Poisson distribution},%
lineskip=-1pt,%
emph={main}
]{exam/DistIntTest.java}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The next program, displayed in Listing~\ref{lst:simplechart},
shows how to export several charts from data tables.
First, three curves are defined with regularly spaced $x$-coordinates
in methods \texttt{getPoints*}; they represent the curves $y = \sqrt x$,
$y = \cos(x)$ and $y = x+2$, respectively. Array \texttt{points[0]} contains
the $x$-coordinates and \texttt{points[1]} the $y$-coordinates
of the points.
Figure~\ref{fig:simplechart-res} presents the resulting chart if the produced
TikZ code is added to a \LaTeX{} document using the \texttt{tikz}
package, and compiled using \LaTeX{}  or Pdf\LaTeX.


\lstinputlisting[label=lst:simplechart,%
caption={Three curves on the same chart},%
lineskip=-1pt,%
emph={getPoints1,getPoints2,getPoints3,main}
]{exam/ChartTest1.java}


\begin{figure}
\input{exam/ChartTest1.tex}
\caption{Results for three curves on the same chart.\label{fig:simplechart-res}}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



The next example, given in Listing~\ref{lst:customchart},
 shows how to customize a chart. First, three curves are defined as
in example~\ref{lst:simplechart} above and the chart is created. Then the
axes are customized by adding labels at chosen values on the $x$-axis.
On the $y$-axis, successive labels are set regularly at points 1 unit apart.
Then the data plot itself is customized. A new color is created in the RGB
model for the first curve which also receives a label name and a dash plot style.
Similarly, the other two curves receive their label name, plot style
 and color. Note that the third curve is drawn in the ORANGE color predefined
 in the AWT package of the standard Java toolkit.
Finally, the charts are exported to a file in \LaTeX{}
format. If the file is compiled with \LaTeX{} or Pdf\LaTeX, the
resulting chart will appear as  displayed in Figure~\ref{fig:customchart-res}.


\lstinputlisting[label=lst:customchart,%
caption={Code for creating and customizing a chart},%
lineskip=-1pt,%
emph={getPoints1,getPoints2,getPoints3,main}
]{exam/ChartTest2.java}


\begin{figure}
\input{exam/ChartTest2.tex}
\caption{A customized chart.\label{fig:customchart-res}}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The next example, given in Listing~\ref{lst:empiricalchart}, shows how to
plot and customize empirical distributions. First, two empirical distributions
are defined from a sample of points obtained from a uniform
generator and a Beta$(3, 1)$ generator, both on the interval
$[0, 1]$. Then an empirical chart is
created to plot these two distributions. The first distribution is plotted
in MAGENTA color with filled square marks from TikZ. The second distribution
uses default color and plot marks. A background grid is also added with cells
of size $0.1\times 0.1$. Finally, the charts are exported to a file in \LaTeX{} format. Figure~\ref{fig:empiricalchart-res} shows the
resulting chart.


\lstinputlisting[label=lst:empiricalchart,%
caption={Creating and customizing empirical distribution charts},%
lineskip=-1pt,%
emph={getPoints1,getPoints2,main}
]{exam/EmpiricalChartTest.java}


\begin{figure}
\input{exam/EmpiricalChartTest.tex}
\caption{A customized empirical distribution chart\label {fig:empiricalchart-res}}
\end{figure}

% \clearpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The next example, given in Listing~\ref{lst:histo1}, shows how to plot
a simple histogram. First,  data is generated from a standard normal.
 Then the plot is customized: 80 bins are selected, and the range of the
  plot is set manually with \texttt{bounds}; the interval is $[-4, 4]$ for
   the $x$-coordinates, and $[0, 5000]$ for the $y$-coordinates.
 Finally, the histogram chart is viewed on the screen, then exported to
  file \texttt{HistogramTest1.tex} in
\LaTeX{} format.  Figure~\ref{fig:histo1-res} displays the resulting chart.


\lstinputlisting[label=lst:histo1,%
caption={Source code creating a simple histogram},%
lineskip=-1pt,%
emph={getData,main}
]{exam/HistogramTest1.java}


\begin{figure}
\input{exam/HistogramTest1.tex}
\caption{A simple histogram for the standard normal density\label{fig:histo1-res}}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The next example, given in Listing~\ref{lst:histochart}, shows how to plot
and customize histograms. First, the two histogram charts \texttt{data1} and
\texttt{data2} are created. Then the data plots are customized: two colors
are selected in the sRGB model from the \texttt{java.awt.Color} package.
40 bins are selected on the interval $[-6, 6]$ for the first histogram.
The number of bins for the second histogram is set automatically.
The range of the plot is set manually with \texttt{bounds}.
 Finally, the two histograms
charts are exported  to file \texttt{HistogramChartTest.tex} in
\LaTeX{} format.  Figure~\ref{fig:histochart-res} displays the resulting chart.


\lstinputlisting[label=lst:histochart,%
caption={Source code creating and customizing histograms.},%
lineskip=-1pt,%
emph={getPoints1,getPoints2,main}
]{exam/HistogramChartTest.java}


\begin{figure}
\input{exam/HistogramChartTest.tex}
\caption{A customized histogram chart\label{fig:histochart-res}}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The next example, given in Listing~\ref{lst:boxplot}, shows how to create
a box-and-whisker plot. First, two series of 1000 points
are obtained from a lognormal distribution and from a Poisson distribution
with $\lambda=5$. These are passed to a \texttt{BoxChart} object, which
creates the boxplot, which can be viewed on screen by executing
the program. We find that the boxplot for the Poisson data (the box on the right
of the chart) has median = 5
(the line inside the box), a mean = 5.009 (the center of the black circle)
the first and the third quartiles at 3 and 6, while the lower and upper
whiskers are at 0 and 10. Finally, there are outliers at 11 and 12 (the hollow
circles) and extreme outliers (the triangle) at 13, outside the chart.
We see that the Poisson data is skewed towards higher values.
A similar description applies to the lognormal data (the box on the left
of the chart), which is strongly skewed towards smaller values.

\lstinputlisting[label=lst:boxplot,%
caption={Source code creating a box-and-whisker plot.},%
lineskip=-1pt,%
emph={main}
]{exam/BoxTest.java}

\vspace{1cm}

\begin{figure}
\begin{center}
\includegraphics[scale=0.5]{exam/BoxTest.png}
\caption{A box-plot\label{fig:boxchart-res}}
\end{center}
\end{figure}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\end{latexonly}
